<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Using advanced Berkeley DB features with dbstl</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="stl.html" title="Chapter 7. Standard Template Library API" />
    <link rel="prev" href="stl_db_usage.html" title="Berkeley DB configuration" />
    <link rel="next" href="stl_txn_usage.html" title="Using transactions in dbstl" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Using advanced Berkeley DB features with dbstl</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="stl_db_usage.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 7. Standard Template Library API</th>
          <td width="20%" align="right"> <a accesskey="n" href="stl_txn_usage.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="stl_db_advanced_usage"></a>Using advanced Berkeley DB features with dbstl</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <dl>
          <dt>
            <span class="sect2">
              <a href="stl_db_advanced_usage.html#idp51421384">Using bulk retrieval iterators</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="stl_db_advanced_usage.html#idp51410312">Using the DB_RMW flag</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="stl_db_advanced_usage.html#idp51398048">Using secondary index database and secondary containers</a>
            </span>
          </dt>
        </dl>
      </div>
      <p>
        This section describes advanced Berkeley DB features that are
        available through dbstl. 
    </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp51421384"></a>Using bulk retrieval iterators</h3>
            </div>
          </div>
        </div>
        <p>
    Bulk retrieval is an optimization option for const iterators and
    nonconst but read-only iterators. Bulk retrieval can minimize the
    number of database accesses performed by your application. It does this
    by reading multiple entries at a time, which reduces read overhead.
    Note that non-sequential reads will benefit less from, or even be hurt
    by, this behavior, because it might result in unneeded data being read
    from the database.  Also, non-serializable reads may read obsolete
    data, because part of the data read from the bulk read buffer may have
    been updated since the retrieval. 
</p>
        <p>
    When using the default transaction isolation, iterators will perform
    serializable reads. In this situation, the bulk-retrieved data cannot
    be updated until the iterator's cursor is closed. 
</p>
        <p>
    Iterators using a different isolation levels, such as
    <a href="../api_reference/C/dbcget.html#dbcget_DB_READ_COMMITTED" class="olink">DB_READ_COMMITTED</a> or <a href="../api_reference/C/dbopen.html#dbopen_DB_READ_UNCOMMITTED" class="olink">DB_READ_UNCOMMITTED</a> will not perform
    serializable reads. The same is true for any iterators that do not use
    transactions.
</p>
        <p>
    A bulk retrieval iterator can only move in a singled direction, from
    beginning to end. This means that iterators only support operator++,
    and reverse iterators only support operator--.
</p>
        <p>
    Iterator objects that use bulk retrieval might contain hundreds of
    kilobytes of data, which makes copying the iterator object an expensive
    operation.  If possible, use ++iterator rather than iterator++. This
    can save a useless copy construction of the iterator, as well as an
    unnecessary dup/close of the cursor. 
</p>
        <p>
    You can configure bulk retrieval for each container using both in the
    const and non-const version of the <code class="methodname">begin()</code>
    method.  The non-const version of <code class="methodname">begin()</code> will
    return a read-only cursor. Note that read-only means something
    different in C++ than it does when referring to an iterator. The latter
    only means that it cannot be used to update the database.
</p>
        <p>
    To configure the bulk retrieval buffer for an iterator when calling the
    <code class="methodname">begin()</code> method, use the
    <code class="function">BulkRetrievelItrOpt::bulk_retrieval(u_int32_t bulk_buffer_size)</code> 
    function.
</p>
        <p>
    If you move a <code class="classname">db_vector_iterator</code> randomly rather
    than sequentially, then dbstl  will not perform bulk retrieval because
    there is little performance gain from bulk retrieval in such an access
    pattern.
</p>
        <p>
    You can call <code class="function">iterator::set_bulk_buffer()</code> to modify
    the iterator's bulk buffer size. Note that once bulk read is enabled,
    only the bulk buffer size can be modified. This means that bulk read
    cannot be disabled. Also, if bulk read was not enabled when you created
    the iterator, you can't enable it after creation.
</p>
        <p>
    Example code using this feature can be found in the
    <code class="methodname">StlAdvancedFeaturesExample::bulk_retrieval_read()</code> method.
</p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp51410312"></a>Using the DB_RMW flag</h3>
            </div>
          </div>
        </div>
        <p>
    The <a href="../api_reference/C/dbcget.html#dbcget_DB_RMW" class="olink">DB_RMW</a> flag is an optimization for non-const (read-write)
    iterators.  This flag causes the underlying cursor to acquire a write
    lock when reading so as to avoid deadlocks. Passing
    <code class="function">ReadModifyWriteOption::read_modify_write()</code> to a
    container's <code class="methodname">begin()</code> method creates an iterator
    whose cursor has this behavior.
</p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp51398048"></a>Using secondary index database and secondary containers</h3>
            </div>
          </div>
        </div>
        <p>
    Because duplicate keys are forbidden in primary databases, only
    <code class="classname">db_map</code>, <code class="classname">db_set</code> and
    <code class="classname">db_vector</code> are allowed to use primary databases.
    For this reason, they are called 
    <span class="bold"><strong>primary containers</strong></span>.  
    A secondary database that supports duplicate keys can be used with
    <code class="classname">db_multimap</code> containers. These are called
    <span class="bold"><strong>secondary containers</strong></span>. Finally, a
    secondary database that forbids duplicate keys can back a
    <code class="classname">db_map</code> container.
</p>
        <p>
    The <span class="bold"><strong>data_type</strong></span> of this
    <code class="classname">db_multimap</code> secondary container is the 
    <span class="bold"><strong>data_type</strong></span> for the primary container. For
    example, a <code class="classname">db_map&lt;int, Person&gt;</code> object
    where the <code class="classname">Person</code> class has an
    <code class="literal">age</code> property of type <code class="literal">size_t</code>, a
    <code class="classname">db_multimap&lt;size_t, Person&gt;</code> using a
    secondary database allows access to a person by age. 
</p>
        <p>

    A container created from a secondary database can only be used to
    iterate, search or delete. It can not be used to update or insert.
    While dbstl does expose the update and insert operations, Berkeley DB
    does not, and an exception will be thrown if attempts are made to
    insert objects into or update objects of a secondary container.
</p>
        <p>
    Example code demonstrating this feature is available in the 
    <code class="methodname">StlAdvancedFeaturesExample::secondary_containers()</code> method.
</p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="stl_db_usage.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="stl.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="stl_txn_usage.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Berkeley DB configuration </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Using transactions in dbstl</td>
        </tr>
      </table>
    </div>
  </body>
</html>
